home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / tcl / SetVar.man < prev    next >
Encoding:
Text File  |  1992-05-08  |  10.6 KB  |  265 lines
  1.  
  2.  
  3.  
  4. Tcl_SetVar            C Library Procedures             Tcl_SetVar
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE                                                               |
  11.      Tcl_SetVar,    Tcl_SetVar2,     Tcl_GetVar,     Tcl_GetVar2,  |
  12.      Tcl_UnsetVar, Tcl_UnsetVar2 - manipulate Tcl variables        |
  13.  
  14. SSYYNNOOPPSSIISS                                                           |
  15.      ##iinncclluuddee <<ttccll..hh>>                                              |
  16.  
  17.      char *                                                        |
  18.      TTccll__SSeettVVaarr(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _n_e_w_V_a_l_u_e, _f_l_a_g_s)                  |
  19.  
  20.      char *                                                        |
  21.      TTccll__SSeettVVaarr22(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _n_e_w_V_a_l_u_e, _f_l_a_g_s)            |
  22.  
  23.      char *                                                        |
  24.      TTccll__GGeettVVaarr(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _f_l_a_g_s)                            |
  25.  
  26.      char *                                                        |
  27.      TTccll__GGeettVVaarr22(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _f_l_a_g_s)                      |
  28.  
  29.      int                                                           |
  30.      TTccll__UUnnsseettVVaarr(_i_n_t_e_r_p, _v_a_r_N_a_m_e, _f_l_a_g_s)                          |
  31.  
  32.      int                                                           |
  33.      TTccll__UUnnsseettVVaarr22(_i_n_t_e_r_p, _n_a_m_e_1, _n_a_m_e_2, _f_l_a_g_s)                    |
  34.  
  35. AARRGGUUMMEENNTTSS                                                          |
  36.      Tcl_Interp   *_i_n_t_e_r_p     (in)                                      ||
  37.                                         Interpreter    containing  |
  38.                                         variable.                  |
  39.  
  40.      char         *_v_a_r_N_a_m_e    (in)                                      ||
  41.                                         Name  of  variable.   May  |
  42.                                         refer to a  scalar  vari-  |
  43.                                         able  or an element of an  |
  44.                                         array variable.            |
  45.  
  46.      char         *_n_e_w_V_a_l_u_e   (in)                                      ||
  47.                                         New value for variable.    |
  48.  
  49.      int          _f_l_a_g_s       (in)                                      ||
  50.                                         OR-ed combination of bits  |
  51.                                         providing      additional  |
  52.                                         information   for  opera-  |
  53.                                         tion. See below for valid  |
  54.                                         values.                    |
  55.  
  56.      char         *_n_a_m_e_1      (in)                                      ||
  57.                                         Name  of scalar variable,  |
  58.                                         or name of array variable  |
  59.                                         if _n_a_m_e_2 is non-NULL.      |
  60.  
  61.  
  62.  
  63. Sprite v1.0                                                     1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Tcl_SetVar            C Library Procedures             Tcl_SetVar
  71.  
  72.  
  73.  
  74.      char         *_n_a_m_e_2      (in)                                      ||
  75.                                         If  non-NULL,  gives name  |
  76.                                         of element  within  array  |
  77.                                         and  _n_a_m_e_1  must refer to  |
  78.                                         an array variable.         |
  79. _________________________________________________________________  |
  80.  
  81.  
  82. DDEESSCCRRIIPPTTIIOONN                                                        |
  83.      These procedures may be used to create,  modify,  read,  and  |
  84.      delete   Tcl   variables   from   C  code.   TTccll__SSeettVVaarr  and  |
  85.      TTccll__SSeettVVaarr22 will create a new variable or modify an existing  |
  86.      one.  Both of these procedures set the given variable to the  |
  87.      value given by _n_e_w_V_a_l_u_e, and they return a pointer to a copy  |
  88.      of  the variable's new value, which is stored in Tcl's vari-  |
  89.      able structure.  Tcl keeps a private copy of the  variable's  |
  90.      value,  so  the  caller may change _n_e_w_V_a_l_u_e after these pro-  |
  91.      cedures return without affecting the value of the  variable.  |
  92.      If  an  error  occurs in setting the variable (e.g. an array  |
  93.      variable is referenced without  giving  an  index  into  the  |
  94.      array), then NULL is returned.                                |
  95.  
  96.      The name of the variable may be specified in either  of  two  |
  97.      ways.   If  TTccll__SSeettVVaarr is called, the variable name is given  |
  98.      as a single string, _v_a_r_N_a_m_e.  If _v_a_r_N_a_m_e  contains  an  open  |
  99.      parenthesis  and  ends  with  a  close parenthesis, then the  |
  100.      value between the parentheses is treated as an index  (which  |
  101.      can  have  any  string  value) and the characters before the  |
  102.      first open parenthesis are treated as the name of  an  array  |
  103.      variable.   If _v_a_r_N_a_m_e doesn't have parentheses as described  |
  104.      above, then the entire string is treated as the  name  of  a  |
  105.      scalar  variable.   If TTccll__SSeettVVaarr22 is called, then the array  |
  106.      name and index have been separated by the  caller  into  two  |
  107.      separate strings, _n_a_m_e_1 and _n_a_m_e_2 respectively;  if _n_a_m_e_2 is  |
  108.      zero it means that a scalar variable is being referenced.     |
  109.  
  110.      The _f_l_a_g_s argument may be used to  specify  any  of  several  |
  111.      options to the procedures.  It consists of an OR-ed combina-  |
  112.      tion of any of the following bits:                            |
  113.  
  114.      TCL_GLOBAL_ONLY                                                    ||
  115.           Under normal circumstances the procedures look up vari-  |
  116.           ables at  the  current  level  of  procedure  call  for  |
  117.           _i_n_t_e_r_p,  or at global level if there is no call active.  |
  118.           However, if this bit is set in _f_l_a_g_s then the  variable  |
  119.           is  looked  up  at global level even if there is a pro-  |
  120.           cedure call active.                                      |
  121.  
  122.      TCL_LEAVE_ERR_MSG                                                  ||
  123.           If  an  error is returned and this bit is set in _f_l_a_g_s,  |
  124.           then an error message will be left  in  _i_n_t_e_r_p->_r_e_s_u_l_t.  |
  125.           If  this  flag  bit  isn't set then no error message is  |
  126.  
  127.  
  128.  
  129. Sprite v1.0                                                     2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Tcl_SetVar            C Library Procedures             Tcl_SetVar
  137.  
  138.  
  139.  
  140.           left (_i_n_t_e_r_p->_r_e_s_u_l_t will not be modified).              |
  141.  
  142.      TCL_APPEND_VALUE                                                   ||
  143.           If  this  bit  is  set then _n_e_w_V_a_l_u_e is appended to the  |
  144.           current value, instead of replacing it.  If  the  vari-  |
  145.           able is currently undefined, then this bit is ignored.   |
  146.  
  147.      TCL_LIST_ELEMENT                                                   ||
  148.           If  this  bit  is  set, then _n_e_w_V_a_l_u_e is converted to a  |
  149.           valid Tcl list element before setting (or appending to)  |
  150.           the variable.  If the list element is being appended to  |
  151.           an non-empty value, then a space character is  appended  |
  152.           before  the new list element to separate it from previ-  |
  153.           ous elements.                                            |
  154.  
  155.      TCL_NO_SPACE                                                       ||
  156.           If  this  bit  is  set,  it  prevents  the  output of a  |
  157.           separating space character in TCL_LIST_ELEMENT appends.  |
  158.           This  bit  has  no  effect  if the TCL_LIST_ELEMENT bit  |
  159.           isn't set.                                               |
  160.  
  161.      TTccll__GGeettVVaarr and TTccll__GGeettVVaarr22 return the  current  value  of  a  |
  162.      variable.   The arguments to these procedures are treated in  |
  163.      the same way as the arguments to TTccll__SSeettVVaarr and TTccll__SSeettVVaarr22.  |
  164.      Under normal circumstances, the return value is a pointer to  |
  165.      the variable's value (which  is  stored  in  Tcl's  variable  |
  166.      structure  and  will  not  change  before  the  next call to  |
  167.      TTccll__SSeettVVaarr or TTccll__SSeettVVaarr22).  The only bits of _f_l_a_g_s that are  |
  168.      used  are  TCL_GLOBAL_ONLY  and  TCL_LEAVE_ERR_MSG,  both of  |
  169.      which have the same meaning as for TTccll__SSeettVVaarr.  If an  error  |
  170.      occurs  in  reading  the variable (e.g. the variable doesn't  |
  171.      exist or an array element is specified for  a  scalar  vari-  |
  172.      able), then NULL is returned.                                 |
  173.  
  174.      TTccll__UUnnsseettVVaarr and TTccll__UUnnsseettVVaarr22 may be used to remove a vari-  |
  175.      able,  so that future calls to TTccll__GGeettVVaarr or TTccll__GGeettVVaarr22 for  |
  176.      the variable will return an error.  The arguments  to  these  |
  177.      procedures  are  treated in the same way as the arguments to  |
  178.      TTccll__GGeettVVaarr and TTccll__GGeettVVaarr22.  If the variable is successfully  |
  179.      removed  then  0  is  returned.   If  the variable cannot be  |
  180.      removed because it doesn't  exist  or  because  a  trace  is  |
  181.      active  for it, then -1 is returned.  If an array element is  |
  182.      specified, the  given  element  is  removed  but  the  array  |
  183.      remains.   If  an  array name is specified without an index,  |
  184.      then the entire array is removed.                             |
  185.  
  186.  
  187. SSEEEE AALLSSOO                                                           |
  188.      Tcl_TraceVar                                                  |
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Sprite v1.0                                                     3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. Tcl_SetVar            C Library Procedures             Tcl_SetVar
  203.  
  204.  
  205.  
  206. KKEEYYWWOORRDDSS                                                           |
  207.      array, interpreter, scalar, set, unset, variable
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.  
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Sprite v1.0                                                     4
  262.  
  263.  
  264.  
  265.